<h1 class="kf">Knopflerfish Android / Dalvik Tutorial</h1>

<h2 class="kf">Contents</h2>
<ol>
  <li><a href="#setup">Setting up the environment</a>
  <li><a href="#building">Building Dalvik dex files</a>
  <li><a href="#runtime">Creating a Dalvik KF run-time</a>
  <li><a href="#install">Installing KF on the Android Emulator</a>
  <li><a href="#run">Running KF under Dalvik</a>
  <li><a href="#projects">Android projects</a>
</ol>


<a name="setup"></a>
<h2 class="kf">Setting up the Environment</h2>
<p>
  To run Knopflerfish on the Android/Dalvik VM you need the Android
  SDK. This SDK contains the necessary tool to convert and pack Java
  classes and JAR files to the DEX format used by Dalvik.  
</p>
<p>
  The KF ant build system has built-in support for dexifying JAR
  files using the tools from the Android SDK.
</p>
<p>
  This guide assumes the SDK for Android 4.0 API level 15 is used.
</p>


<a name="runtime"></a>
<h2 class="kf">Building Dalvik dex files</h2>
<p>
  The KF ant build system has support to create the necessary dex
  files for the framework and all the bundles. For any bundle, the
  framework, or the whole KF distribution dex versions can be built by
  specifying <tt>ANDROID_HOME</tt> to the build target.
</p>
<pre class="shell">
 &gt; ant -DANDROID_HOME=&gt;path to android sdk top directory  &lt;
</pre>
<p>
  It is recommended you build the dex files on a clean distribution. 
</p>
<p>
  The generated dex files are places in the bundle's JAR file
  as <tt>classes.dex</tt> directly in the root. The Java class files
  are still kept in the JAR file. This means the same bundle can run
  on a normal JVM as well as with Dalvik without any
  modifications. From a size perspective this is of course not optimal
  to include both Java classes and classes.dex. A bundle get roughly
  twice as large after dexifying it. 
  Future KF releases may have support to create pure dex version of
  bundles.</p>
<p>
  After building or dexifying KF the push the necessary files to the
  emulator, typically using <tt>adb</tt>. There is since KF 3.3 an
  android tool included to simplify this process, see next section.
</p>
<a name="runtime"></a>
<h2 class="kf">Creating a Dalvik KF run-time</h2>
<p>
  The KF distribution contains a simple build tool to create and install KF
  on an Android emulator. It is located in the <tt>tools/android</tt>
  directory.
</p>
<p>
  After specifying 
  After stepping into this directory run <tt>ant</tt> and specify
  where the Android SDK is installed:
  <pre class="shell">
 &gt; cd tools/android
 &gt; ant setup -DANDROID_HOME=/Users/knopflerfish/bin/android-sdk-mac_x86/  
  </pre>
  Specifying <tt>ANDROID_HOME</tt> is only necessary  the first time
  you run ant. The location is stored in
  the android.properties file located in the same directory. You can
  run the setup target again, pointing at another location if needed.
  <pre class="shell">
 &gt; ant setup -DANDROID_HOME=/bin/android-sdk
  </pre>
</p>
<p>
  There is a small template xargs file included. This contains a very
  basic set of bundles. Feel free to modify or add additional xargs files.
</p>
<p>
  The build will create the run time in:
  <pre class="shell">
  &gt; out/dalvik
  </pre>

<a name="install"></a>
<h2 class="kf">Installing KF on the Android/Dalvik Emulator</h2>
<p>
  The build.xml file includes an <tt>install</tt> target. This will
  install the created KF run time on the emulator using
  the <tt>adb</tt> tools. For this to function the Android emulator
  must be running of course.
  <pre class="shell">
  &gt; ant install
  </pre>

  The files are installed in <tt>/data/kf-3.3.0</tt> by default on the emulator.
</p>

<a name="run"></a>
<h2 class="kf">Running KF under Dalvik</h2>
<p>
  To launch KF under Dalvik you need to start Dalvik in the
  emulator. This is typically done by starting a shell on the emulator:
</p>
<pre class="shell">
  &gt; adb shell
  root@android:/ #   
  root@android:/ # cd /data/kf-3.3.0/                                          
  root@android:/data/kf-3.3.0 # 
  root@android:/data/kf-3.3.0 # ls
  dalvik.xargs
  framework.jar
  jars
  props.xargs
  root@android:/data/kf-3.3.0 # 
</pre>
  The next step is to launch KF. This is done as usual, but using
  the <tt>dalvikvm</tt> instead.
<pre class="shell">
  root@android:/data/kf-3.3.0 # dalvikvm -classpath framework.jar \
  org.knopflerfish.framework.Main -xargs dalvik.xargs
</pre>
  Now KF is running under the dalvik VM! The ttyconsole bundle is included in
  the dalvik.xargs. In the emulator shell window you can interact with
  the KF framework just as you are used to:
<pre class="shell">
 &gt; lsb
   id  level/state name
   --------------------
    0  0/active    System Bundle            1  1/active    Log Service
    2  1/active    cm                       3  1/active    Console
    4  1/active    Event-Admin              5  2/resolved  util-LIB
    6  2/resolved  JSDK-API                 7  4/active    HTTP-Server
    8  5/active    FW-Commands-IMPL         9  5/active    LogCommands-IMPL
   10  5/active    CM-Commands-IMPL        11  5/active    TTY-Console-IMPL
   12  7/active    HTTP-root-IMPL       
 &gt;     
</pre>
  To  verify we are successfully running the KF HTTP server use the
  browser in Android emulator and connect to the KF HTTP server running on port
  8080:
<p>
  <img src="images/dalvik_httproot.png" border="0" alt="httproot on
  Android" />
</p>
  
<h3 class="kf">Note on Running KF under Dalvik</h3>
<p>
  The framework will create <jar>.dexopt files that lives side-by-side
  with the jar files. This can cause a problem if your bundles lives
  in a read-only directory and have the property (which is default):
  <pre class="shell">
  -Forg.knopflerfish.framework.bundlestorage.file.reference=true
  </pre>
  You then need to set the property to false, so that the bundle jars
  are copied into the "fwdir".
</p>

<a name="projects"></a>
<h2 class="kf">Android Projects</h2>
<p>
  The latest version of KF added the <tt>apk</tt> directory
  to <tt>tools/android</tt>. Here you can find two Android projects
  that can be used to build an Android <tt>.apk</tt> containing
  Knopflerfish, see the README.txt file in the <tt>projects</tt>
  directory for more information.
</p>
<p>
  <img src="images/android_app.png" border="0" alt="Android
  application" />
</p>
<p>
  These projects are built using a combination of KF and the Android ant
  tasks. Bundles that you include in your <tt>.apk</tt> will be dexified
  as described above and DEX files for <tt>framework.jar</tt> and Java
  classes included in the projects will be automatically created by the
  build system. 
</p>


